<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>MRtrix documentation</title>
<link rel="stylesheet" href="../stylesheet.css" type="text/css" media=screen>
</head>

<body>

<table class=nav>
  <tr>
    <td><a href="index.html"><img src="../left.png"></a></td>
    <td><a href="index.html"><img src="../up.png"></a></td>
    <td><a href="../index.html"><img src="../home.png"></a></td>
    <th>Unix/Linux</th>
    <td><a href="windows.html"><img src="../right.png"></a></td>
  </tr>
</table>



<p>
MRtrix depends on a number of other packages. 
Most, if not all of these packages should be available on any recent Linux distribution via the appropriate package manager.
MRtrix has been written and tested on Ubuntu Linux 7.10 (Gutsy) and 8.04 (Hardy).
On both these distributions, all dependencies are available via the Synaptic Package Manager.
</p>

<h2><a name='builddeps'>Compile-time dependencies</a></h2>
<p>
Before any of the programs included in the MRtrix packages can be used, they need to be <em>compiled</em> 
(i.e. translated into machine code suitable for your specific computer platform).
This will generate the required <em>executables</em> and dynamic library.
The following packages and corresponding development files (i.e. headers) are required for this step:
</p>
<dl>
  <dt>g++ - the GNU C++ compiler (version &gt; 4.0.0 recommended)</dt>
  <dd>available from <a href="http://gcc.gnu.org/">http://gcc.gnu.org/</a></dd>
  <dt>python (version &gt; 2.5 recommended)</dt>
  <dd>available from <a href="http://www.python.org/">http://www.python.org/</a></dd>
  <dt>glib (version &gt; 2.16)</dt>
  <dt>gtk+ (version &gt; 2.12)</dt>
  <dd>both available from <a href="http://www.gtk.org/">http://www.gtk.org/</a></dd>
  <dt>glibmm (version &gt; 2.16)</dt>
  <dt>gtkmm (version &gt; 2.12)</dt>
  <dd>both available from <a href="http://www.gtkmm.org/">http://www.gtkmm.org/</a></dd>
  <dt>gtkglext (version &gt; 1.0)</dt>
  <dd>available from <a href="http://www.k-3d.org/gtkglext/Main_Page">http://www.k-3d.org/gtkglext/Main_Page</a></dd>
  <dt>GSL (GNU Scientific Library; version &gt; 1.8)</dt>
  <dd>available from <a href="http://www.gnu.org/software/gsl/">http://www.gnu.org/software/gsl/</a></dd>
  <dt>a working OpenGL implementation (version &gt; 1.2)</dt>
  <dd>for best results on Linux, we recommend the use of an nVidia&reg; graphics card together with the nVidia&reg; proprietory drivers. 
  These drivers may be available via the distribution package manager (this is the case with Ubuntu Linux). 
  If not, they can be downloaded from <a href="http://www.nvidia.com/">http://www.nvidia.com/</a></dd>
</dl>
<p>
On Ubuntu, these packages can be installed via the Synaptic Package Manager (or apt-get) by searching for the following packages:
</p>
<ul>
  <li>g++</li>
  <li>python2.5</li>
  <li>libglib2.0-dev</li>
  <li>libgtk2.0-dev</li>
  <li>libglibmm-2.4-dev</li>
  <li>libgtkmm-2.4-dev</li>
  <li>libgtkglext1-dev</li>
  <li>libgsl0-dev</li>
  <li>libgl1-mesa-dev (for a generic OpenGL implementation);<br>The nVidia&reg; driver already includes the required development files</li>
  <li>libglu1-mesa-dev</li>
</ul>



<p class=sep><a href="#top">top</a></p>

<h2><a name='rundeps'>Run-time dependencies</a></h2>
<p>
Once all the executables have been compiled (as in the previous steps), 
they can be used provided the following packages are also installed.
Note that these should already be installed on your system, 
either by default or as a result of having installed the corresponding development packages in the previous compilation step.
</p>
<dl>
  <dt>glib (version &gt; 2.16)</dt>
  <dt>gtk+ (version &gt; 2.12)</dt>
  <dd>both available from <a href="http://www.gtk.org/">http://www.gtk.org/</a></dd>
  <dt>glibmm (version &gt; 2.16)</dt>
  <dt>gtkmm (version &gt; 2.12)</dt>
  <dd>both available from <a href="http://www.gtkmm.org/">http://www.gtkmm.org/</a></dd>
  <dt>gtkglext (version &gt; 1.0)</dt>
  <dd>available from <a href="http://www.k-3d.org/gtkglext/Main_Page">http://www.k-3d.org/gtkglext/Main_Page</a></dd>
  <dt>GSL (GNU Scientific Library; version &gt; 1.8)</dt>
  <dd>available from <a href="http://www.gnu.org/software/gsl/">http://www.gnu.org/software/gsl/</a></dd>
  <dt>a working OpenGL implementation (version &gt; 1.2)</dt>
  <dd>for best results on Linux, we recommend the use of an nVidia&reg; graphics card together with the nVidia&reg; proprietory drivers. 
  These drivers may be available via the distribution package manager (this is the case with Ubuntu Linux). 
  If not, they can be downloaded from <a href="http://www.nvidia.com/">http://www.nvidia.com/</a></dd>
</dl>
<p>
On Ubuntu, these packages can be installed via the Synaptic Package Manager (or apt-get) by searching for the following packages:
</p>
<ul>
  <li>libglib2.0</li>
  <li>libgtk2.0</li>
  <li>libglibmm-2.4</li>
  <li>libgtkmm-2.4</li>
  <li>libgtkglext1</li>
  <li>libgsl</li>
  <li>libgl1-mesa-glx (for a generic OpenGL implementation);<br>nvidia-glx or nvidia-glx-new (if using a nVidia&reg; graphics card)</li>
  <li>libglu1-mesa</li>
</ul>



<p class=sep><a href="#top">top</a></p>

<h2><a name='compile'>Compilation from source</a></h2>
<p>
Once all dependencies are installed, MRtrix can be compiled by issuing the command (modify as appropriate):
</p>
<pre>
&gt; <b>tar xjf mrtrix-0.2.6.tar.bz2</b>
&gt; <b>cd mrtrix-0.2.6/</b>
&gt; <b>./build</b>
</pre>
<p>
If this completes with no errors, all executables should be located in the <kbd>bin/</kbd> folder, 
and the <kbd>libmrtrix-0_2_6.so</kbd> dynamic library should be located in the <kbd>lib/</kbd> folder.
</p>
<p>
If any errors do occur, you may need to modify the configuration file.
The relevant file will be located in the <kbd>sysconfig/</kbd> folder,
will have a <kbd>*.py</kbd> suffix, and will be named according to the target platform.
Unfortunately a full discussion of the various options that can be modified is beyond the scope of this document.
</p>

<p class=sep><a href="#top">top</a></p>
<h3><a name='x86-64'>Compilation on 64-bit systems (x86-64)</a></h3>
<p>
MRtrix can be compiled in 64-bit mode by editing the <kbd>sysconf/linux.py</kbd> file prior to issuing the <kbd>./build</kbd> command.
Note that MRtrix will run just as well in 32-bit mode on these systems; 
enabling 64-bit mode allows MRtrix to access a larger address space,
and consequently to process larger data sets. 
If you need to process very large data sets (i.e. 2GB or more), then compiling MRtrix in 64-bit mode may be recommended.
</p>
<p>
To enable 64-bit mode, open the <kbd>sysconf/linux.py</kbd> file using a text editor:
</p>
<pre>
&gt; <b>gedit sysconf/linux.py</b>
</pre>
<p>
Find the line that specifies the C++ compiler flags, and change the <kbd>-march</kbd> option to <kbd>x86-64</kbd> 
(note the use of a hyphen, rather than an underscore as produced by the <kbd>uname</kbd> command).
The modified line should now read:
</p>
<pre>
cpp_flags = [ '-Wall', '-march=<b>x86-64</b>', '-fPIC', '-fno-strict-aliasing', '-DGL_GLEXT_PROTOTYPES' ]
</pre>
<p>
Save the file and exit the editor. You can now issue the <kbd>./build</kbd> command to carry out the compilation itself.
</p>
<p>
<strong>Note:</strong> if you had issued the <kbd>./build</kbd> command at any point before editing the <kbd>sysconf/linux.py</kbd> file,
you will most likely need to remove any intermediate files that may have already been generated. 
To do this, issue the commands:
</p>
<pre>
&gt; <b>./build clean</b>
&gt; <b>./build</b>
</pre>


<p class=sep><a href="#top">top</a></p>


<h2><a name='install'>Installation of executables</a></h2>
<p>
Once all executables and the dynamic library have been successfully created, they can be made available for use.
The recommended installation procedure is as follows (note that this can be tailored to your needs).
The following commands will need to be issued from the <em>root</em> account.
If you do not have root or administrative access to your system, you can simply install the files to a location that
you have write permissions for (i.e. anywhere in your home folder), in which case the following commands can be issued from your own account.
</p>
<p>
<b>Note:</b> on Ubuntu and other systems without a <em>root</em> account, 
simply type <kbd>sudo</kbd> as the first word on the command line 
(see <a href="https://help.ubuntu.com/community/RootSudo">this page</a> for details).
</p>

<h3>1. copy the executables to a suitable location</h3>
<p>
A suitable location on most Unix/Linux systems is <kbd>/opt/</kbd> or <kbd>/usr/local/</kbd>, although any other location is equally valid.
In this example, the executables will be placed in <kbd>/opt/</kbd>. 
If you wish to install MRtrix in a different location, simply replace all occurences of <kbd>/opt</kbd> with the desired path.
<p>
There are several ways to copy the required files. You can either copy the entire installation folder:
</p>
<pre>
# <b>cp -r . /opt/mrtrix</b>
</pre>
<p>
Or just copy the executables and library:
</p>
<pre>
# <b>mkdir -p /opt/mrtrix/bin /opt/mrtrix/lib</b>
# <b>cp -r bin/* /opt/mrtrix/bin</b>
# <b>cp lib/libmrtrix-0_2_6.so /opt/mrtrix/lib</b>
</pre>
<p>
<strong>Note:</strong> you may need to alter file access permissions to allow non-root users to run the executables.
This can be done using <kbd>chmod</kbd>:
</p>
<pre>
# <b>chmod -R a+rX /opt/mrtrix/</b>
</pre>


<h3>2. set the correct search paths</h3>
<p>
In order to run the commands from the command line, you will need to set two parameters:
the command search path, and the library search path. The procedure for this will depend on your system.
On certain systems, it may be possible to set these variables for all users (requires root access).
Otherwise, it is relatively simple to set up individual user accounts for MRtrix.
</p>
<h4>System-wide installation (all users)</h4>
<p>
Each unix variant may use a different procedure to set up the user's environment upon login.
On Ubuntu Linux, the file <kbd>/etc/environment</kbd> is used to set environment variables. 
On other systems, the relevant file may be <kbd>/etc/profile</kbd>.
Simply open the relevant file as root:
</p>
<pre>
&gt; <b>sudo gedit /etc/environment</b>
</pre>
<p>
and modify the <kbd>PATH</kbd> variable by adding the <kbd>/opt/mrtrix/bin</kbd> folder.
When you are done, the relevant line in the file should look something like this:
<p>
<pre>
PATH="/opt/mrtrix/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
</pre>
<p>
You also need to add the folder containing the dynamic library to the system search path.
This can be done by  creating a file called <kbd>/etc/ld.so.conf.d/mrtrix.conf</kbd>, 
containing the path to the relevant folder. 
The following procedure should be sufficient:
</p>
<pre>
# <b>gedit /etc/ld.so.conf.d/mrtrix.conf</b>
</pre>
<p>
add the line:
</p>
<pre>
/opt/mrtrix/lib
</pre>
<p>
save the file, and issue the following command:
</p>
<pre>
# <b>ldconfig</b>
</pre>
<p>
Once you have logged out and back in again, you should be able to call all MRtrix commands directly.
You can check your installation by typing:
</p>
<pre>
&gt; <b><a href='../commands/mrview.html'>mrview</a></b>
</pre>
<p>
which should open the MRtrix viewing tool.
</p>



<h4>Single user installation</h4>
<p>
A single user account can be set up to use MRtrix by editing one of the startup scripts.
Unfortunately, there is no unique solution here, as distributions vary in their conventions.
The simplest solution is to modify your shell's 'rc' script.
Note that in this case the programs will only run when launched from the shell (i.e. from the command-line), 
which should not be a problem in most cases.
First, find out which shell you are using:
</p>
<pre>
&gt; <b>echo $SHELL</b>
</pre>
<p>
For the Bourne-again shell (/bin/bash), edit the <kbd>.bashrc</kbd> file in your home directory:
</p>
<pre>
&gt; <b>gedit ~/.bashrc</b>
</pre>
<p>
and add the following two lines at the end of the file:
</p>
<pre>
export PATH=/opt/mrtrix/bin:$PATH
export LD_LIBRARY_PATH=/opt/mrtrix/lib/
</pre>
<p>
For the Berkeley C shell (/bin/csh or /bin/tcsh), edit the <kbd>.cshrc</kbd> file in your home directory:
</p>
<pre>
&gt; <b>gedit ~/.cshrc</b>
</pre>
<p>
and add the following two lines at the end of the file:
</p>
<pre>
setenv PATH /opt/mrtrix/bin:$PATH
setenv LD_LIBRARY_PATH /opt/mrtrix/lib/
</pre>
<p>
You should now be able to run MRtrix executables from the command-line 
(note that you may need to open a new terminal or even log out before the changes take effect).
You can check your installation by typing:
</p>
<pre>
&gt; <b><a href='../commands/mrview.html'>mrview</a></b>
</pre>
<p>
which should open the MRtrix viewing tool.
</p>

<p class=sep><a href="#top">top</a></p>


<h2><a name='config'>Final configuration</a></h2>
<p>
Once the software is up and running, is it worth taking the time to perform a few simple configurations steps.
The following important application behaviours can be modified by setting the relevant variables 
in the <a href='../appendix/config.html'>configuration file</a> (described in more detail
in the <a href='../appendix/config.html'>Appendix</a>).
Note that if the configuration file does not exist, or if the variables are not set, 
default values will be used instead.
</p>
<dl>
  <dt>Enable multi-threading</dt>
  <dd>If MRtrix is installed on a multi-processor or multi-core system, some of the more CPU intensive
  tasks can take advantage of this by performing the processing in parallel across some or all of the CPU cores.
  Currently, the <a href='../tractography/preprocess.html#csd'>CSD computation</a> and
  <a href='../tractography/tracking.html'>tractography</a> programs are both ready 
  for multi-threading, and will therefore take substantially less time if multi-threading is enabled.
  This is done by adding the following line to your <a href='../appendix/config.html'>configuration file</a>:
  <pre>NumberOfThreads: 4</pre> with the number set appropriately for your system.</dd>

  <dt>Left-right convention for Analyse images</dt>
  <dd>There is some ambiguity in the Analyse format as to whether images are stored in left to right order
  or in the reverse order. This can lead to a great deal of confusion, and for this reason, it is not recommended 
  to use the Analyse format if it can be avoided. For those cases when you need to use this format, 
  the left-right ordering convention can be set by adding this line to your <a href='../appendix/config.html'>configuration file</a>:
  <pre>Analyse.LeftToRight: false</pre>
  By default, Analyse images are assumed to be stored left to right.</dd>
</dl>





<table class=nav>
  <tr>
    <td><a href="index.html"><img src="../left.png"></a></td>
    <td><a href="index.html"><img src="../up.png"></a></td>
    <td><a href="../index.html"><img src="../home.png"></a></td>
    <th><a href='#top'>top</a></th>
    <td><a href="windows.html"><img src="../right.png"></a></td>
  </tr>
</table>

</body>
</html>

